Aller au contenu principal

2. Métadonnées du client

Les clients enregistrés ont un ensemble de valeurs de métadonnées associées à leur identifiant client sur un serveur d'autorisation, telles que la liste des URI de redirection valides ou un nom d'affichage.

Ces valeurs de métadonnées client sont utilisées de deux manières :

  • comme valeurs d'entrée pour les demandes d'enregistrement, et

  • comme valeurs de sortie dans les réponses d'enregistrement.

Les champs de métadonnées client suivants sont définis par cette spécification. La mise en œuvre et l'utilisation de tous les champs de métadonnées client sont OPTIONNELLES, sauf indication contraire. Tous les types de membres de données (chaînes, tableaux, nombres) sont définis en termes de leurs représentations JSON [RFC7159].

redirect_uris Tableau de chaînes d'URI de redirection à utiliser dans les flux basés sur la redirection tels que le code d'autorisation et les flux implicites. Comme exigé par la section 2 d'OAuth 2.0 [RFC6749], les clients utilisant des flux avec redirection DOIVENT enregistrer leurs valeurs d'URI de redirection. Les serveurs d'autorisation qui prennent en charge l'enregistrement dynamique pour les flux basés sur la redirection DOIVENT mettre en œuvre la prise en charge de cette valeur de métadonnées.

token_endpoint_auth_method Indicateur de chaîne de la méthode d'authentification demandée pour le point de terminaison de jeton. Les valeurs définies par cette spécification sont :

  • "none" : Le client est un client public tel que défini dans OAuth 2.0, Section 2.1, et ne possède pas de secret client.

  • "client_secret_post" : Le client utilise les paramètres HTTP POST tels que définis dans OAuth 2.0, Section 2.3.1.

  • "client_secret_basic" : Le client utilise HTTP Basic tel que défini dans OAuth 2.0, Section 2.3.1.

Des valeurs supplémentaires peuvent être définies via le registre IANA "OAuth Token Endpoint Authentication Methods" établi dans la section 4.2. Les URI absolus peuvent également être utilisés comme valeurs pour ce paramètre sans être enregistrés. Si non spécifié ou omis, la valeur par défaut est "client_secret_basic", désignant le schéma d'authentification HTTP Basic tel que spécifié dans la section 2.3.1 d'OAuth 2.0.

grant_types Tableau de chaînes de type d'autorisation OAuth 2.0 que le client peut utiliser au niveau du point de terminaison de jeton. Ces types d'autorisation sont définis comme suit :

  • "authorization_code" : Le type d'autorisation de code d'autorisation défini dans OAuth 2.0, Section 4.1.

  • "implicit" : Le type d'autorisation implicite défini dans OAuth 2.0, Section 4.2.

  • "password" : Le type d'autorisation des identifiants de mot de passe du propriétaire de la ressource défini dans OAuth 2.0, Section 4.3.

  • "client_credentials" : Le type d'autorisation des identifiants client défini dans OAuth 2.0, Section 4.4.

  • "refresh_token" : Le type d'autorisation de jeton d'actualisation défini dans OAuth 2.0, Section 6.

  • "urn:ietf:params:oauth:grant-type:jwt-bearer" : Le type d'autorisation de jeton porteur JWT défini dans les profils de jeton porteur OAuth JWT [RFC7523].

  • "urn:ietf:params:oauth:grant-type:saml2-bearer" : Le type d'autorisation d'assertion SAML 2.0 Bearer défini dans les profils de jeton porteur OAuth SAML 2 [RFC7522].

Si le point de terminaison de jeton est utilisé dans le type d'autorisation, la valeur de ce paramètre DOIT être la même que la valeur du paramètre "grant_type" passé au point de terminaison de jeton défini dans la définition du type d'autorisation. Les serveurs d'autorisation PEUVENT autoriser d'autres valeurs telles que définies dans le processus d'extension du type d'autorisation décrit dans OAuth 2.0, Section 4.5. Si omis, le comportement par défaut est que le client n'utilisera que le type d'autorisation "authorization_code".

response_types Tableau des chaînes de type de réponse OAuth 2.0 que le client peut utiliser au niveau du point de terminaison d'autorisation. Ces types de réponse sont définis comme suit :

  • "code" : Le type de réponse de code d'autorisation défini dans OAuth 2.0, Section 4.1.

  • "token" : Le type de réponse implicite défini dans OAuth 2.0, Section 4.2.

Si le point de terminaison d'autorisation est utilisé par le type d'autorisation, la valeur de ce paramètre DOIT être la même que la valeur du paramètre "response_type" passé au point de terminaison d'autorisation définie dans la définition du type d'autorisation. Les serveurs d'autorisation PEUVENT autoriser d'autres valeurs telles que définies dans le processus d'extension de type de réponse décrit dans OAuth 2.0, Section 4.5. Si omis, la valeur par défaut est que le client n'utilisera que le type de réponse "code".

client_name Nom en chaîne lisible par l'homme du client à présenter à l'utilisateur final lors de l'autorisation. Si omis, le serveur d'autorisation PEUT afficher la valeur brute "client_id" à l'utilisateur final à la place. Il est RECOMMANDÉ que les clients envoient toujours ce champ. La valeur de ce champ PEUT être internationalisée, comme décrit à la section 2.2.

client_uri Chaîne d'URL d'une page Web fournissant des informations sur le client. Si présent, le serveur DEVRAIT afficher cette URL à l'utilisateur final sous forme cliquable. Il est RECOMMANDÉ que les clients envoient toujours ce champ. La valeur de ce champ DOIT pointer vers une page Web valide. La valeur de ce champ PEUT être internationalisée, comme décrit à la section 2.2.

logo_uri Chaîne d'URL qui référence un logo pour le client. Si présent, le serveur DEVRAIT afficher cette image à l'utilisateur final lors de l'approbation. La valeur de ce champ DOIT pointer vers un fichier image valide. La valeur de ce champ PEUT être internationalisée, comme décrit à la section 2.2.

scope Chaîne contenant une liste de valeurs de portée séparées par des espaces (comme décrit dans la section 3.3 d'OAuth 2.0 [RFC6749]) que le client peut utiliser lors de la demande de jetons d'accès. La sémantique des valeurs de cette liste est spécifique au service. Si omis, un serveur d'autorisation PEUT enregistrer un client avec un ensemble de portées par défaut.

contacts Tableau de chaînes représentant des moyens de contacter les personnes responsables de ce client, généralement des adresses e-mail. Le serveur d'autorisation PEUT rendre ces adresses de contact disponibles aux utilisateurs finaux pour les demandes d'assistance pour le client. Voir la section 6 pour des informations sur les considérations de confidentialité.

tos_uri Chaîne d'URL qui pointe vers un document de conditions de service lisible par l'homme pour le client qui décrit une relation contractuelle entre l'utilisateur final et le client que l'utilisateur final accepte lors de l'autorisation du client. Le serveur d'autorisation DEVRAIT afficher cette URL à l'utilisateur final si elle est fournie. La valeur de ce champ DOIT pointer vers une page Web valide. La valeur de ce champ PEUT être internationalisée, comme décrit à la section 2.2.

policy_uri Chaîne d'URL qui pointe vers un document de politique de confidentialité lisible par l'homme qui décrit comment l'organisation de déploiement collecte, utilise, conserve et divulgue les données personnelles. Le serveur d'autorisation DEVRAIT afficher cette URL à l'utilisateur final si elle est fournie. La valeur de ce champ DOIT pointer vers une page Web valide. La valeur de ce champ PEUT être internationalisée, comme décrit à la section 2.2.

jwks_uri Chaîne d'URL référençant le document JSON Web Key (JWK) Set [RFC7517] du client, qui contient les clés publiques du client. La valeur de ce champ DOIT pointer vers un document JWK Set valide. Ces clés peuvent être utilisées par des protocoles de niveau supérieur qui utilisent la signature ou le chiffrement. Par exemple, ces clés peuvent être utilisées par certaines applications pour valider les demandes signées faites au point de terminaison de jeton lors de l'utilisation de JWT pour l'authentification du client [RFC7523]. L'utilisation de ce paramètre est préférée au paramètre "jwks", car elle permet une rotation plus facile des clés. Les paramètres "jwks_uri" et "jwks" NE DOIVENT PAS être présents tous les deux dans la même requête ou réponse.

jwks Valeur du document JSON Web Key Set [RFC7517] du client, qui contient les clés publiques du client. La valeur de ce champ DOIT être un objet JSON contenant un JWK Set valide. Ces clés peuvent être utilisées par des protocoles de niveau supérieur qui utilisent la signature ou le chiffrement. Ce paramètre est destiné à être utilisé par les clients qui ne peuvent pas utiliser le paramètre "jwks_uri", tels que les clients natifs qui ne peuvent pas héberger d'URL publiques. Les paramètres "jwks_uri" et "jwks" NE DOIVENT PAS être présents tous les deux dans la même requête ou réponse.

software_id Une chaîne d'identification unique (par exemple, un identifiant unique universel (UUID)) attribuée par le développeur client ou l'éditeur de logiciel utilisée par les points de terminaison d'enregistrement pour identifier le logiciel client à enregistrer dynamiquement. Contrairement à "client_id", qui est émis par le serveur d'autorisation et DEVRAIT varier entre les instances, le "software_id" DEVRAIT rester le même pour toutes les instances du logiciel client. Le "software_id" DEVRAIT rester le même à travers plusieurs mises à jour ou versions du même logiciel. La valeur de ce champ n'est pas destinée à être lisible par l'homme et est généralement opaque pour le client et le serveur d'autorisation.

software_version Une chaîne d'identifiant de version pour le logiciel client identifié par "software_id". La valeur de "software_version" DEVRAIT changer à chaque mise à jour du logiciel client identifié par le même "software_id". La valeur de ce champ est destinée à être comparée en utilisant une correspondance d'égalité de chaîne et aucune autre sémantique de comparaison n'est définie par cette spécification. La valeur de ce champ est hors du champ d'application de cette spécification, mais elle n'est pas destinée à être lisible par l'homme et est généralement opaque pour le client et le serveur d'autorisation. La définition de ce qui constitue une mise à jour du logiciel client qui déclencherait un changement de cette valeur est spécifique au logiciel lui-même et est hors du champ d'application de cette spécification.

Les extensions et profils de cette spécification peuvent étendre cette liste avec des noms et descriptions de métadonnées enregistrés conformément aux considérations IANA de la section 4 de ce document. Le serveur d'autorisation DOIT ignorer toute métadonnée client envoyée par le client qu'il ne comprend pas (par exemple, en supprimant silencieusement les métadonnées inconnues de l'enregistrement du client lors du traitement). Le serveur d'autorisation PEUT rejeter toute valeur de métadonnée client demandée en remplaçant les valeurs demandées par des valeurs par défaut appropriées comme décrit à la section 3.2.1 ou en renvoyant une réponse d'erreur comme décrit à la section 3.2.2.

Les valeurs de métadonnées client peuvent être communiquées directement dans le corps d'une demande d'enregistrement, comme décrit à la section 3.1, ou incluses comme revendications dans une déclaration logicielle, comme décrit à la section 2.3 ; un mélange des deux est également possible. Si le même nom de métadonnée client est présent aux deux emplacements et que la déclaration logicielle est approuvée par le serveur d'autorisation, la valeur d'une revendication dans la déclaration logicielle DOIT prévaloir.

2.1. Relation entre les types d'autorisation et les types de réponse​

Les valeurs "grant_types" et "response_types" décrites ci-dessus sont partiellement orthogonales, car elles font référence à des arguments passés à différents points de terminaison dans le protocole OAuth. Cependant, elles sont liées en ce sens que les "grant_types" disponibles pour un client influencent les "response_types" que le client est autorisé à utiliser, et vice versa. Par exemple, une valeur "grant_types" qui inclut "authorization_code" implique une valeur "response_types" qui inclut "code", car les deux valeurs sont définies dans le cadre de l'autorisation de code OAuth 2.0. En tant que tel, un serveur prenant en charge ces champs DEVRAIT prendre des mesures pour s'assurer qu'un client ne peut pas s'enregistrer dans un état incohérent, par exemple, en renvoyant une réponse d'erreur "invalid_client_metadata" à une demande d'enregistrement incohérente.

La corrélation entre les deux champs est répertoriée dans le tableau ci-dessous.

valeur grant_types inclut :valeur response_types inclut :
authorization_codecode
implicittoken
password(aucun)
client_credentials(aucun)
refresh_token(aucun)
urn:ietf:params:oauth:grant-type:jwt-bearer(aucun)
urn:ietf:params:oauth:grant-type:saml2-bearer(aucun)

Les extensions et profils de ce document qui introduisent de nouvelles valeurs pour le paramètre "grant_types" ou "response_types" DOIVENT documenter toutes les correspondances entre ces deux types de paramètres.

2.2. Métadonnées client lisibles par l'homme​

Les valeurs de métadonnées client lisibles par l'homme et les valeurs de métadonnées client qui référencent des valeurs lisibles par l'homme PEUVENT être représentées dans plusieurs langues et scripts. Par exemple, les valeurs de champs tels que "client_name", "tos_uri", "policy_uri", "logo_uri" et "client_uri" peuvent avoir plusieurs valeurs spécifiques aux paramètres régionaux dans certains enregistrements de clients pour faciliter l'utilisation dans différents emplacements.

Pour spécifier les langues et les scripts, des balises de langue BCP 47 [RFC5646] sont ajoutées aux noms de membres de métadonnées client, délimitées par un caractère "#". Étant donné que les noms de membres JSON [RFC7159] sont sensibles à la casse, il est RECOMMANDÉ que les valeurs de balise de langue utilisées dans les noms de revendications soient épelées en utilisant la casse de caractères avec laquelle elles sont enregistrées dans le registre "IANA Language Subtag" [IANA.Language]. En particulier, les noms de langue sont normalement épelés avec des caractères minuscules, les noms de région sont épelés avec des caractères majuscules et les langues sont épelées avec des caractères à casse mixte. Cependant, étant donné que les valeurs de balise de langue BCP 47 sont insensibles à la casse, les implémentations DEVRAIENT interpréter les valeurs de balise de langue fournies de manière insensible à la casse. Conformément aux recommandations de la BCP 47, les valeurs de balise de langue utilisées dans les noms de membres de métadonnées ne doivent être aussi spécifiques que nécessaire. Par exemple, l'utilisation de "fr" peut être suffisante dans de nombreux contextes, plutôt que "fr-CA" ou "fr-FR".

Par exemple, un client pourrait représenter son nom en anglais comme "client_name#en": "My Client" et son nom en japonais comme "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D" dans la même demande d'enregistrement. Le serveur d'autorisation PEUT afficher l'un ou la totalité de ces noms au propriétaire de la ressource lors de l'étape d'autorisation, en choisissant le nom à afficher en fonction de la configuration du système, des préférences de l'utilisateur ou d'autres facteurs.

Si un champ lisible par l'homme est envoyé sans balise de langue, les parties l'utilisant NE DOIVENT PAS faire d'hypothèses sur la langue, le jeu de caractères ou le script de la valeur de chaîne, et la valeur de chaîne DOIT être utilisée telle quelle partout où elle est présentée dans une interface utilisateur. Pour faciliter l'interopérabilité, il est RECOMMANDÉ que les clients et les serveurs utilisent un champ lisible par l'homme sans balise de langue en plus de tout champ spécifique à la langue, et il est RECOMMANDÉ que tout champ lisible par l'homme envoyé sans balise de langue contienne des valeurs adaptées à l'affichage sur une grande variété de systèmes.

Note de l'implémenteur : De nombreuses bibliothèques JSON permettent de référencer les membres d'un objet JSON en tant que membres d'une construction d'objet dans l'environnement de programmation natif de la bibliothèque. Cependant, bien que le caractère "#" soit un caractère valide à l'intérieur des noms de membres d'un objet JSON, ce n'est pas un caractère valide pour une utilisation dans un nom de membre d'objet dans de nombreux environnements de programmation. Par conséquent, les implémentations devront utiliser des formes d'accès alternatives pour ces revendications. Par exemple, en JavaScript, si l'on analyse le JSON comme suit, "var j = JSON.parse(json);", alors comme solution de contournement, le membre "client_name#en-us" peut être accédé en utilisant la syntaxe JavaScript "j["client_name#en-us"]".

2.3. Déclaration logicielle​

Une déclaration logicielle est un JSON Web Token (JWT) [RFC7519] qui affirme des valeurs de métadonnées sur le logiciel client sous forme de paquet. Un ensemble de revendications pouvant être utilisées dans une déclaration logicielle est défini dans la section 2. Lorsqu'elle est présentée au serveur d'autorisation dans le cadre d'une demande d'enregistrement client, la déclaration logicielle DOIT être signée numériquement ou MACée à l'aide de JSON Web Signature (JWS) [RFC7515] et DOIT contenir une revendication "iss" (émetteur) désignant la partie attestant des revendications dans la déclaration logicielle. Il est RECOMMANDÉ que les déclarations logicielles soient signées numériquement à l'aide de l'algorithme de signature "RS256", bien que des applications particulières PUISSENT spécifier l'utilisation d'algorithmes différents. Il est RECOMMANDÉ que les déclarations logicielles contiennent la revendication "software_id" pour permettre aux serveurs d'autorisation de corréler différentes instances de logiciel utilisant la même déclaration logicielle.

Par exemple, une déclaration logicielle pourrait contenir les revendications suivantes :

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

L'exemple non normatif suivant de JWT inclut ces revendications et a été signé de manière asymétrique à l'aide de "RS256" (avec des sauts de ligne à des fins d'affichage uniquement) :

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

La déclaration logicielle est généralement distribuée avec toutes les instances d'une application client. Les moyens par lesquels un client ou un développeur obtient une déclaration logicielle sont hors du champ d'application de cette spécification. Certaines méthodes courantes pourraient inclure un développeur client générant un JWT spécifique au client en s'enregistrant auprès d'un éditeur d'API logicielle pour obtenir une déclaration logicielle pour une classe de clients.

Les critères selon lesquels les serveurs d'autorisation déterminent s'ils doivent faire confiance et utiliser les informations contenues dans une déclaration logicielle sont hors du champ d'application de cette spécification.

Dans certains cas, les serveurs d'autorisation PEUVENT choisir d'accepter une valeur de déclaration logicielle directement comme identifiant client dans une demande d'autorisation, sans qu'un enregistrement dynamique préalable du client ait été effectué. Les circonstances dans lesquelles un serveur d'autorisation le ferait, et les caractéristiques spécifiques de la déclaration logicielle requises dans ce cas, sont hors du champ d'application de cette spécification.

Dernière mise à jour le