3. Endpoint di registrazione del client

L'endpoint di registrazione del client è un endpoint OAuth 2.0 definito in questo documento progettato per consentire a un client di essere registrato presso il server di autorizzazione. L'endpoint di registrazione del client DEVE accettare messaggi HTTP POST con parametri di richiesta codificati nel corpo dell'entità utilizzando il formato "application/json". L'endpoint di registrazione del client DEVE essere protetto da un meccanismo di sicurezza del livello di trasporto, come descritto nella Sezione 5.

L'endpoint di registrazione del client PUÒ essere una risorsa protetta OAuth 2.0 [RFC6749] e PUÒ accettare un token di accesso iniziale sotto forma di un token di accesso OAuth 2.0 per limitare la registrazione solo alle parti precedentemente autorizzate. Il metodo con cui il token di accesso iniziale viene ottenuto dal client o dallo sviluppatore è generalmente fuori banda ed è al di fuori dell'ambito di questa specifica. Il metodo con cui il token di accesso iniziale viene verificato e convalidato dall'endpoint di registrazione del client è al di fuori dell'ambito di questa specifica.

Per supportare la registrazione aperta e facilitare una più ampia interoperabilità, l'endpoint di registrazione del client DOVREBBE consentire richieste di registrazione senza autorizzazione (vale a dire, senza token di accesso iniziale nella richiesta). Queste richieste POSSONO essere limitate in frequenza o altrimenti limitate per prevenire un attacco di denial-of-service all'endpoint di registrazione del client.

3.1. Richiesta di registrazione del client

Questa operazione registra un client presso il server di autorizzazione. Il server di autorizzazione assegna a questo client un identificativo client univoco, assegna facoltativamente un segreto client e associa i metadati forniti nella richiesta con l'identificativo client emesso. La richiesta include tutti i parametri dei metadati del client specificati per il client durante la registrazione. Il server di autorizzazione PUÒ fornire valori predefiniti per qualsiasi elemento omesso nei metadati del client.

Per registrarsi, il client o lo sviluppatore invia un HTTP POST all'endpoint di registrazione del client con un tipo di contenuto di "application/json". Il payload dell'entità HTTP è un documento JSON [RFC7159] costituito da un oggetto JSON e da tutti i valori dei metadati del client richiesti come membri di primo livello di quell'oggetto JSON.

Ad esempio, se il server supporta la registrazione aperta (senza token di accesso iniziale), il client potrebbe inviare la seguente richiesta di registrazione all'endpoint di registrazione del client.

Di seguito è riportato un esempio di richiesta non normativa che non utilizza un token di accesso iniziale:

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"
}

In alternativa, se il server supporta la registrazione autorizzata, allo sviluppatore o al client verrà fornito un token di accesso iniziale. (Il metodo con cui viene ottenuto il token di accesso iniziale è al di fuori dell'ambito di questa specifica.) Lo sviluppatore o il client invia la seguente richiesta di registrazione autorizzata all'endpoint di registrazione del client. Si noti che il token di accesso iniziale inviato in questo esempio è un token bearer OAuth 2.0 [RFC6750], ma qualsiasi tipo di token OAuth 2.0 potrebbe essere utilizzato da un server di autorizzazione.

Di seguito è riportato un esempio di richiesta non normativa che utilizza un token di accesso iniziale e registra un JWK Set per valore (con interruzioni di riga all'interno dei valori solo a scopo di visualizzazione):

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. Richiesta di registrazione del client utilizzando una dichiarazione software

Oltre agli elementi JSON, i valori dei metadati del client POSSONO essere forniti anche in una dichiarazione software, come descritto nella Sezione 2.3. Il server di autorizzazione PUÒ ignorare la dichiarazione software se non supporta questa funzionalità. Se il server supporta le dichiarazioni software, i valori dei metadati del client trasmessi nella dichiarazione software DEVONO avere la precedenza su quelli trasmessi utilizzando semplici elementi JSON.

Le dichiarazioni software sono incluse nell'oggetto JSON richiedente utilizzando questo membro OPZIONALE:

software_statement Una dichiarazione software contenente valori di metadati del client sul software client come claim. Questo è un valore stringa contenente l'intero JWT firmato.

Nell'esempio seguente, alcuni parametri di registrazione sono trasmessi come claim in una dichiarazione software dall'esempio nella Sezione 2.3, mentre alcuni valori specifici per l'istanza client sono trasmessi come parametri regolari (con interruzioni di riga all'interno dei valori solo a scopo di visualizzazione):

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. Risposte

A seguito di una richiesta di registrazione riuscita, il server di autorizzazione restituisce un identificativo client per il client. Il server risponde con un codice di stato HTTP 201 Created e un corpo di tipo "application/json" con contenuto come descritto nella Sezione 3.2.1.

A seguito di una richiesta di registrazione non riuscita, il server di autorizzazione risponde con un errore, come descritto nella Sezione 3.2.2.

3.2.1. Risposta alle informazioni sul client

La risposta contiene l'identificativo client e il segreto client, se il client è un client riservato. La risposta PUÒ contenere campi aggiuntivi specificati dalle estensioni di questa specifica.

client_id OBBLIGATORIO. Stringa dell'identificativo client OAuth 2.0. DOVREBBE NON essere attualmente valida per nessun altro client registrato, sebbene un server di autorizzazione POSSA emettere lo stesso identificativo client a più istanze di un client registrato a sua discrezione.

client_secret OPZIONALE. Stringa del segreto client OAuth 2.0. Se emesso, questo DEVE essere univoco per ogni "client_id" e DOVREBBE essere univoco per più istanze di un client che utilizzano lo stesso "client_id". Questo valore è utilizzato dai client riservati per autenticarsi all'endpoint del token, come descritto in OAuth 2.0 [RFC6749], Sezione 2.3.1.

client_id_issued_at OPZIONALE. Ora in cui è stato emesso l'identificativo client. L'ora è rappresentata come il numero di secondi dal 1970-01-01T00:00:00Z misurato in UTC fino alla data/ora di emissione.

client_secret_expires_at OBBLIGATORIO se viene emesso "client_secret". Ora in cui scadrà il segreto client o 0 se non scadrà. L'ora è rappresentata come il numero di secondi dal 1970-01-01T00:00:00Z misurato in UTC fino alla data/ora di scadenza.

Inoltre, il server di autorizzazione DEVE restituire tutti i metadati registrati su questo client, inclusi eventuali campi forniti dal server di autorizzazione stesso. Il server di autorizzazione PUÒ rifiutare o sostituire uno qualsiasi dei valori dei metadati richiesti dal client inviati durante la registrazione e sostituirli con valori adatti. Il client o lo sviluppatore può controllare i valori nella risposta per determinare se la registrazione è sufficiente per l'uso (ad esempio, il "token_endpoint_auth_method" registrato è supportato dal software client) e determinare una linea d'azione appropriata per il software client. La risposta a una tale situazione è al di fuori dell'ambito di questa specifica ma potrebbe includere la presentazione di un report allo sviluppatore dell'applicazione o al provider del server di autorizzazione, il tentativo di nuova registrazione con valori di metadati diversi o vari altri metodi. Ad esempio, se il server supporta anche un meccanismo di gestione della registrazione come quello definito in [RFC7592], il client o lo sviluppatore potrebbe tentare di aggiornare la registrazione con valori di metadati diversi. Questo processo potrebbe anche essere aiutato da un protocollo di scoperta dei servizi, come [OpenID.Discovery], che può elencare le capacità di un server, consentendo a un client di effettuare una richiesta di registrazione più informata. L'uso di un tale sistema di gestione o scoperta è facoltativo e al di fuori dell'ambito di questa specifica.

La risposta di registrazione riuscita utilizza un codice di stato HTTP 201 Created con un corpo di tipo "application/json" costituito da un singolo oggetto JSON [RFC7159] con tutti i parametri come membri di primo livello dell'oggetto.

Se una dichiarazione software è stata utilizzata come parte della registrazione, il suo valore DEVE essere restituito non modificato nella risposta insieme ad altri metadati utilizzando il nome del membro "software_statement". Gli elementi dei metadati del client utilizzati dalla dichiarazione software DEVONO essere restituiti direttamente anche come valori dei metadati del client di primo livello nella risposta di registrazione (possibilmente con valori diversi, poiché i valori richiesti e i valori utilizzati potrebbero differire).

Di seguito è riportato un esempio non normativo di risposta di una registrazione riuscita:

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. Risposta di errore di registrazione del client

Quando si verifica una condizione di errore OAuth 2.0, come il client che presenta un token di accesso iniziale non valido, il server di autorizzazione restituisce una risposta di errore appropriata al tipo di token OAuth 2.0.

Quando si verifica una condizione di errore di registrazione, il server di autorizzazione restituisce un codice di stato HTTP 400 (se non diversamente specificato) con tipo di contenuto "application/json" costituito da un oggetto JSON [RFC7159] che descrive l'errore nel corpo della risposta.

Due membri sono definiti per l'inclusione nell'oggetto JSON:

error OBBLIGATORIO. Stringa di codice di errore ASCII singola.

error_description OPZIONALE. Descrizione testuale ASCII leggibile dall'uomo dell'errore utilizzata per il debug.

Altri membri POSSONO anche essere inclusi e, se non vengono compresi, DEVONO essere ignorati.

Questa specifica definisce i seguenti codici di errore:

invalid_redirect_uri Il valore di uno o più URI di reindirizzamento non è valido.

invalid_client_metadata Il valore di uno dei campi dei metadati del client non è valido e il server ha rifiutato questa richiesta. Si noti che un server di autorizzazione PUÒ scegliere di sostituire un valore valido per qualsiasi parametro richiesto dei metadati di un client.

invalid_software_statement La dichiarazione software presentata non è valida.

unapproved_software_statement La dichiarazione software presentata non è approvata per l'uso da parte di questo server di autorizzazione.

Di seguito è riportato un esempio non normativo di una risposta di errore risultante da un URI di reindirizzamento che è stato inserito nella lista nera dal server di autorizzazione (con interruzioni di riga all'interno dei valori solo a scopo di visualizzazione):

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."
}

Di seguito è riportato un esempio non normativo di una risposta di errore risultante da una combinazione incoerente di valori "response_types" e "grant_types" (con interruzioni di riga all'interno dei valori solo a scopo di visualizzazione):

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."
}