2. Metadati del client

I client registrati hanno un insieme di valori di metadati associati al loro identificativo client presso un server di autorizzazione, come un elenco di URI di reindirizzamento validi o un nome visualizzato.

Questi valori di metadati del client sono utilizzati in due modi:

• come valori di input per le richieste di registrazione, e

• come valori di output nelle risposte di registrazione.

I seguenti campi di metadati del client sono definiti da questa specifica. L'implementazione e l'uso di tutti i campi di metadati del client è OPZIONALE, salvo diversa indicazione. Tutti i tipi di membri dati (stringhe, array, numeri) sono definiti in termini delle loro rappresentazioni JSON [RFC7159].

redirect_uris Array di stringhe di URI di reindirizzamento da utilizzare nei flussi basati su reindirizzamento come il flusso del codice di autorizzazione e il flusso implicito. Come richiesto da OAuth 2.0 [RFC6749], Sezione 2, i client che utilizzano flussi con reindirizzamento DEVONO registrare i loro valori di URI di reindirizzamento. I server di autorizzazione che supportano la registrazione dinamica per flussi basati su reindirizzamento DEVONO implementare il supporto per questo valore di metadati.

token_endpoint_auth_method Indicatore stringa del metodo di autenticazione richiesto per l'endpoint del token. I valori definiti da questa specifica sono:

• "none": Il client è un client pubblico come definito in OAuth 2.0, Sezione 2.1, e non ha un segreto client.

• "client_secret_post": Il client utilizza i parametri HTTP POST come definito in OAuth 2.0, Sezione 2.3.1.

• "client_secret_basic": Il client utilizza HTTP Basic come definito in OAuth 2.0, Sezione 2.3.1.

Ulteriori valori possono essere definiti tramite il registro IANA "OAuth Token Endpoint Authentication Methods" stabilito nella Sezione 4.2. Gli URI assoluti possono anche essere utilizzati come valori per questo parametro senza essere registrati. Se non specificato o omesso, il valore predefinito è "client_secret_basic", che denota lo schema di autenticazione HTTP Basic come specificato nella Sezione 2.3.1 di OAuth 2.0.

grant_types Array di stringhe di tipo di concessione OAuth 2.0 che il client può utilizzare all'endpoint del token. Questi tipi di concessione sono definiti come segue:

• "authorization_code": Il tipo di concessione del codice di autorizzazione definito in OAuth 2.0, Sezione 4.1.

• "implicit": Il tipo di concessione implicita definito in OAuth 2.0, Sezione 4.2.

• "password": Il tipo di concessione delle credenziali della password del proprietario della risorsa definito in OAuth 2.0, Sezione 4.3.

• "client_credentials": Il tipo di concessione delle credenziali del client definito in OAuth 2.0, Sezione 4.4.

• "refresh_token": Il tipo di concessione del token di aggiornamento definito in OAuth 2.0, Sezione 6.

• "urn:ietf:params:oauth:grant-type:jwt-bearer": Il tipo di concessione del token bearer JWT definito in OAuth JWT Bearer Token Profiles [RFC7523].

• "urn:ietf:params:oauth:grant-type:saml2-bearer": La concessione di asserzione bearer SAML 2.0 definita in OAuth SAML 2 Bearer Token Profiles [RFC7522].

Se l'endpoint del token è utilizzato nel tipo di concessione, il valore di questo parametro DEVE essere lo stesso del valore del parametro "grant_type" passato all'endpoint del token definito nella definizione del tipo di concessione. I server di autorizzazione POSSONO consentire altri valori come definiti nel processo di estensione del tipo di concessione descritto in OAuth 2.0, Sezione 4.5. Se omesso, il comportamento predefinito è che il client utilizzerà solo il tipo di concessione "authorization_code".

response_types Array di stringhe di tipo di risposta OAuth 2.0 che il client può utilizzare all'endpoint di autorizzazione. Questi tipi di risposta sono definiti come segue:

• "code": Il tipo di risposta del codice di autorizzazione definito in OAuth 2.0, Sezione 4.1.

• "token": Il tipo di risposta implicita definito in OAuth 2.0, Sezione 4.2.

Se l'endpoint di autorizzazione è utilizzato dal tipo di concessione, il valore di questo parametro DEVE essere lo stesso del valore del parametro "response_type" passato all'endpoint di autorizzazione definito nella definizione del tipo di concessione. I server di autorizzazione POSSONO consentire altri valori come definiti nel processo di estensione del tipo di risposta descritto in OAuth 2.0, Sezione 4.5. Se omesso, il valore predefinito è che il client utilizzerà solo il tipo di risposta "code".

client_name Nome stringa leggibile dall'uomo del client da presentare all'utente finale durante l'autorizzazione. Se omesso, il server di autorizzazione PUÒ visualizzare invece il valore grezzo "client_id" all'utente finale. Si RACCOMANDA che i client inviino sempre questo campo. Il valore di questo campo PUÒ essere internazionalizzato, come descritto nella Sezione 2.2.

client_uri Stringa URL di una pagina web che fornisce informazioni sul client. Se presente, il server DOVREBBE visualizzare questo URL all'utente finale in forma cliccabile. Si RACCOMANDA che i client inviino sempre questo campo. Il valore di questo campo DEVE puntare a una pagina web valida. Il valore di questo campo PUÒ essere internazionalizzato, come descritto nella Sezione 2.2.

logo_uri Stringa URL che fa riferimento a un logo per il client. Se presente, il server DOVREBBE visualizzare questa immagine all'utente finale durante l'approvazione. Il valore di questo campo DEVE puntare a un file immagine valido. Il valore di questo campo PUÒ essere internazionalizzato, come descritto nella Sezione 2.2.

scope Stringa contenente un elenco separato da spazi di valori di ambito (come descritto nella Sezione 3.3 di OAuth 2.0 [RFC6749]) che il client può utilizzare quando richiede token di accesso. La semantica dei valori in questo elenco è specifica del servizio. Se omesso, un server di autorizzazione PUÒ registrare un client con un set di ambiti predefinito.

contacts Array di stringhe che rappresentano modi per contattare le persone responsabili di questo client, tipicamente indirizzi email. Il server di autorizzazione PUÒ rendere questi indirizzi di contatto disponibili agli utenti finali per le richieste di supporto per il client. Vedere la Sezione 6 per informazioni sulle considerazioni sulla privacy.

tos_uri Stringa URL che punta a un documento di termini di servizio leggibile dall'uomo per il client che descrive una relazione contrattuale tra l'utente finale e il client che l'utente finale accetta quando autorizza il client. Il server di autorizzazione DOVREBBE visualizzare questo URL all'utente finale se fornito. Il valore di questo campo DEVE puntare a una pagina web valida. Il valore di questo campo PUÒ essere internazionalizzato, come descritto nella Sezione 2.2.

policy_uri Stringa URL che punta a un documento di informativa sulla privacy leggibile dall'uomo che descrive come l'organizzazione di distribuzione raccoglie, utilizza, conserva e divulga i dati personali. Il server di autorizzazione DOVREBBE visualizzare questo URL all'utente finale se fornito. Il valore di questo campo DEVE puntare a una pagina web valida. Il valore di questo campo PUÒ essere internazionalizzato, come descritto nella Sezione 2.2.

jwks_uri Stringa URL che fa riferimento al documento JSON Web Key (JWK) Set [RFC7517] del client, che contiene le chiavi pubbliche del client. Il valore di questo campo DEVE puntare a un documento JWK Set valido. Queste chiavi possono essere utilizzate da protocolli di livello superiore che utilizzano firma o crittografia. Ad esempio, queste chiavi potrebbero essere utilizzate da alcune applicazioni per convalidare le richieste firmate fatte all'endpoint del token quando si utilizzano JWT per l'autenticazione del client [RFC7523]. L'uso di questo parametro è preferito rispetto al parametro "jwks", in quanto consente una rotazione delle chiavi più semplice. I parametri "jwks_uri" e "jwks" NON DEVONO essere entrambi presenti nella stessa richiesta o risposta.

jwks Valore del documento JSON Web Key Set [RFC7517] del client, che contiene le chiavi pubbliche del client. Il valore di questo campo DEVE essere un oggetto JSON contenente un JWK Set valido. Queste chiavi possono essere utilizzate da protocolli di livello superiore che utilizzano firma o crittografia. Questo parametro è destinato all'uso da parte di client che non possono utilizzare il parametro "jwks_uri", come i client nativi che non possono ospitare URL pubblici. I parametri "jwks_uri" e "jwks" NON DEVONO essere entrambi presenti nella stessa richiesta o risposta.

software_id Una stringa identificativa unica (ad es., un Universally Unique Identifier, UUID) assegnata dallo sviluppatore del client o dall'editore del software utilizzata dagli endpoint di registrazione per identificare il software client da registrare dinamicamente. A differenza di "client_id", che è emesso dal server di autorizzazione e DOVREBBE variare tra le istanze, il "software_id" DOVREBBE rimanere lo stesso per tutte le istanze del software client. Il "software_id" DOVREBBE rimanere lo stesso attraverso più aggiornamenti o versioni dello stesso software. Il valore di questo campo non è inteso per essere leggibile dall'uomo ed è solitamente opaco per il client e il server di autorizzazione.

software_version Una stringa identificativa di versione per il software client identificato da "software_id". Il valore di "software_version" DOVREBBE cambiare a ogni aggiornamento del software client identificato dallo stesso "software_id". Il valore di questo campo è destinato a essere confrontato utilizzando una corrispondenza di uguaglianza di stringa e nessun'altra semantica di confronto è definita da questa specifica. Il valore di questo campo è al di fuori dell'ambito di questa specifica, ma non è inteso per essere leggibile dall'uomo ed è solitamente opaco per il client e il server di autorizzazione. La definizione di cosa costituisce un aggiornamento del software client che innescherebbe un cambiamento di questo valore è specifica del software stesso ed è al di fuori dell'ambito di questa specifica.

Le estensioni e i profili di questa specifica possono estendere questo elenco con nomi e descrizioni di metadati registrati in conformità con le Considerazioni IANA nella Sezione 4 di questo documento. Il server di autorizzazione DEVE ignorare qualsiasi metadato del client inviato dal client che non comprende (ad es., eliminando silenziosamente i metadati sconosciuti dal record di registrazione del client durante l'elaborazione). Il server di autorizzazione PUÒ rifiutare qualsiasi valore di metadati del client richiesto, sostituendo i valori richiesti con valori predefiniti appropriati come descritto nella Sezione 3.2.1, o restituendo una risposta di errore come descritto nella Sezione 3.2.2.

I valori dei metadati del client possono essere comunicati direttamente nel corpo di una richiesta di registrazione, come descritto nella Sezione 3.1, o inclusi come claim in una dichiarazione software, come descritto nella Sezione 2.3; è anche possibile una combinazione di entrambi. Se lo stesso nome di metadati del client è presente in entrambe le posizioni e la dichiarazione software è attendibile per il server di autorizzazione, il valore di un claim nella dichiarazione software DEVE avere la precedenza.

2.1. Relazione tra tipi di concessione e tipi di risposta

I valori "grant_types" e "response_types" descritti sopra sono parzialmente ortogonali, in quanto si riferiscono ad argomenti passati a diversi endpoint nel protocollo OAuth. Tuttavia, sono correlati in quanto i "grant_types" disponibili per un client influenzano i "response_types" che il client è autorizzato a utilizzare, e viceversa. Ad esempio, un valore "grant_types" che include "authorization_code" implica un valore "response_types" che include "code", poiché entrambi i valori sono definiti come parte della concessione del codice di autorizzazione OAuth 2.0. Pertanto, i server che supportano questi campi DOVREBBERO adottare misure per garantire che un client non possa registrarsi in uno stato incoerente, ad esempio, restituendo una risposta di errore "invalid_client_metadata" a una richiesta di registrazione incoerente.

La correlazione tra i due campi è elencata nella tabella seguente.

valore grant_types include:	valore response_types include:
authorization_code	code
implicit	token
password	(nessuno)
client_credentials	(nessuno)
refresh_token	(nessuno)
urn:ietf:params:oauth:grant-type:jwt-bearer	(nessuno)
urn:ietf:params:oauth:grant-type:saml2-bearer	(nessuno)

Le estensioni e i profili di questo documento che introducono nuovi valori per il parametro "grant_types" o "response_types" DEVONO documentare tutte le corrispondenze tra questi due tipi di parametro.

2.2. Metadati del client leggibili dall'uomo

I valori dei metadati del client leggibili dall'uomo e i valori dei metadati del client che fanno riferimento a valori leggibili dall'uomo POSSONO essere rappresentati in più lingue e script. Ad esempio, i valori dei campi come "client_name", "tos_uri", "policy_uri", "logo_uri" e "client_uri" potrebbero avere più valori specifici della locale in alcune registrazioni dei client per facilitare l'uso in luoghi diversi.

Per specificare lingue e script, i tag di lingua BCP 47 [RFC5646] vengono aggiunti ai nomi dei membri dei metadati del client, delimitati da un carattere "#". Poiché i nomi dei membri JSON [RFC7159] sono sensibili alle maiuscole/minuscole, si RACCOMANDA che i valori dei tag di lingua utilizzati nei nomi dei claim siano scritti utilizzando la combinazione di maiuscole e minuscole con cui sono registrati nel registro "IANA Language Subtag" [IANA.Language]. In particolare, i nomi delle lingue sono normalmente scritti con caratteri minuscoli, le regioni sono scritte con caratteri maiuscoli e le lingue sono scritte con caratteri misti. Tuttavia, poiché i valori dei tag di lingua BCP 47 non sono sensibili alle maiuscole/minuscole, le implementazioni DOVREBBERO interpretare i valori dei tag di lingua forniti in modo non sensibile alle maiuscole/minuscole. Coerentemente con le raccomandazioni in BCP 47, i valori dei tag di lingua utilizzati nei nomi dei membri dei metadati dovrebbero essere specifici solo quanto necessario. Ad esempio, l'uso di "fr" potrebbe essere sufficiente in molti contesti, piuttosto che "fr-CA" o "fr-FR".

Ad esempio, un client potrebbe rappresentare il suo nome inglese come "client_name#en": "My Client" e il suo nome giapponese come "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D" nella stessa richiesta di registrazione. Il server di autorizzazione PUÒ visualizzare uno o tutti questi nomi al proprietario della risorsa durante la fase di autorizzazione, scegliendo quale nome visualizzare in base alla configurazione del sistema, alle preferenze dell'utente o ad altri fattori.

Se un campo leggibile dall'uomo viene inviato senza un tag di lingua, le parti che lo utilizzano NON DEVONO fare alcuna ipotesi sulla lingua, il set di caratteri o lo script del valore della stringa, e il valore della stringa DEVE essere utilizzato così com'è ovunque sia presentato in un'interfaccia utente. Per facilitare l'interoperabilità, si RACCOMANDA che client e server utilizzino un campo leggibile dall'uomo senza alcun tag di lingua oltre a qualsiasi campo specifico della lingua, e si RACCOMANDA che qualsiasi campo leggibile dall'uomo inviato senza un tag di lingua contenga valori adatti alla visualizzazione su un'ampia varietà di sistemi.

Nota per l'implementatore: Molte librerie JSON consentono di fare riferimento ai membri di un oggetto JSON come membri di un costrutto di oggetto nell'ambiente di programmazione nativo della libreria. Tuttavia, sebbene il carattere "#" sia un carattere valido all'interno dei nomi dei membri dell'oggetto JSON, non è un carattere valido per l'uso in un nome membro dell'oggetto in molti ambienti di programmazione. Pertanto, le implementazioni dovranno utilizzare forme di accesso alternative per accedere a questi claim. Ad esempio, in JavaScript, se si analizza il JSON come segue, "var j = JSON.parse(json);", allora come soluzione alternativa, al membro "client_name#en-us" è possibile accedere utilizzando la sintassi JavaScript "j["client_name#en-us"]".

2.3. Dichiarazione software

Una dichiarazione software è un JSON Web Token (JWT) [RFC7519] che asserisce valori di metadati sul software client come un pacchetto. Un insieme di claim che possono essere utilizzati in una dichiarazione software è definito nella Sezione 2. Quando presentata al server di autorizzazione come parte di una richiesta di registrazione del client, la dichiarazione software DEVE essere firmata digitalmente o MACed utilizzando JSON Web Signature (JWS) [RFC7515] e DEVE contenere un claim "iss" (emittente) che denota la parte che attesta i claim nella dichiarazione software. Si RACCOMANDA che le dichiarazioni software siano firmate digitalmente utilizzando l'algoritmo di firma "RS256", sebbene particolari applicazioni POSSANO specificare l'uso di algoritmi diversi. Si RACCOMANDA che le dichiarazioni software contengano il claim "software_id" per consentire ai server di autorizzazione di correlare diverse istanze di software che utilizzano la stessa dichiarazione software.

Ad esempio, una dichiarazione software potrebbe contenere i seguenti claim:

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

Il seguente esempio non normativo di JWT include questi claim ed è stato firmato asimmetricamente utilizzando "RS256" (con interruzioni di riga solo a scopo di visualizzazione):

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

La dichiarazione software è tipicamente distribuita con tutte le istanze di un'applicazione client. I mezzi con cui un client o uno sviluppatore ottiene una dichiarazione software sono al di fuori dell'ambito di questa specifica. Alcuni metodi comuni potrebbero includere uno sviluppatore client che genera un JWT specifico per il client registrandosi presso un editore di API software per ottenere una dichiarazione software per una classe di client.

I criteri con cui i server di autorizzazione determinano se fidarsi e utilizzare le informazioni in una dichiarazione software sono al di fuori dell'ambito di questa specifica.

In alcuni casi, i server di autorizzazione POSSONO scegliere di accettare un valore di dichiarazione software direttamente come identificativo client in una richiesta di autorizzazione, senza che sia stata eseguita alcuna registrazione dinamica del client precedente. Le circostanze in cui un server di autorizzazione farebbe ciò e le caratteristiche specifiche della dichiarazione software richieste in questo caso, sono al di fuori dell'ambito di questa specifica.