Aller au contenu principal

3. Point de terminaison d'enregistrement de client

Le point de terminaison d'enregistrement de client est un point de terminaison OAuth 2.0 défini dans ce document qui est conçu pour permettre à un client d'être enregistré auprès du serveur d'autorisation. Le point de terminaison d'enregistrement de client DOIT accepter les messages HTTP POST avec des paramètres de requête codés dans le corps de l'entité en utilisant le format "application/json". Le point de terminaison d'enregistrement de client DOIT être protégé par un mécanisme de sécurité de la couche transport, comme décrit à la section 5.

Le point de terminaison d'enregistrement de client PEUT être une ressource protégée OAuth 2.0 [RFC6749] et il PEUT accepter un jeton d'accès initial sous la forme d'un jeton d'accès OAuth 2.0 pour limiter l'enregistrement aux seules parties précédemment autorisées. La méthode par laquelle le jeton d'accès initial est obtenu par le client ou le développeur est généralement hors bande et hors du champ d'application de cette spécification. La méthode par laquelle le jeton d'accès initial est vérifié et validé par le point de terminaison d'enregistrement de client est hors du champ d'application de cette spécification.

Pour prendre en charge l'enregistrement ouvert et faciliter une interopérabilité plus large, le point de terminaison d'enregistrement de client DEVRAIT autoriser les demandes d'enregistrement sans autorisation (c'est-à-dire sans jeton d'accès initial dans la demande). Ces demandes PEUVENT être limitées en débit ou autrement limitées pour empêcher une attaque par déni de service sur le point de terminaison d'enregistrement de client.

3.1. Demande d'enregistrement de client​

Cette opération enregistre un client auprès du serveur d'autorisation. Le serveur d'autorisation attribue à ce client un identifiant client unique, attribue éventuellement un secret client et associe les métadonnées fournies dans la demande à l'identifiant client émis. La demande inclut tous les paramètres de métadonnées client spécifiés pour le client lors de l'enregistrement. Le serveur d'autorisation PEUT fournir des valeurs par défaut pour tout élément omis dans les métadonnées client.

Pour s'enregistrer, le client ou le développeur envoie un HTTP POST au point de terminaison d'enregistrement de client avec un type de contenu de "application/json". La charge utile de l'entité HTTP est un document JSON [RFC7159] composé d'un objet JSON et de toutes les valeurs de métadonnées client demandées en tant que membres de niveau supérieur de cet objet JSON.

Par exemple, si le serveur prend en charge l'enregistrement ouvert (sans jeton d'accès initial), le client pourrait envoyer la demande d'enregistrement suivante au point de terminaison d'enregistrement de client.

Ce qui suit est un exemple de demande non normative n'utilisant pas de jeton d'accès initial :

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

Alternativement, si le serveur prend en charge l'enregistrement autorisé, le développeur ou le client recevra un jeton d'accès initial. (La méthode par laquelle le jeton d'accès initial est obtenu est hors du champ d'application de cette spécification.) Le développeur ou le client envoie la demande d'enregistrement autorisée suivante au point de terminaison d'enregistrement de client. Notez que le jeton d'accès initial envoyé dans cet exemple est un jeton porteur OAuth 2.0 [RFC6750], mais tout type de jeton OAuth 2.0 pourrait être utilisé par un serveur d'autorisation.

Ce qui suit est un exemple de demande non normative utilisant un jeton d'accès initial et enregistrant un JWK Set par valeur (avec des sauts de ligne dans les valeurs à des fins d'affichage uniquement) :

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. Demande d'enregistrement de client à l'aide d'une déclaration logicielle​

En plus des éléments JSON, les valeurs de métadonnées client PEUVENT également être fournies dans une déclaration logicielle, comme décrit à la section 2.3. Le serveur d'autorisation PEUT ignorer la déclaration logicielle s'il ne prend pas en charge cette fonctionnalité. Si le serveur prend en charge les déclarations logicielles, les valeurs de métadonnées client transmises dans la déclaration logicielle DOIVENT prévaloir sur celles transmises à l'aide d'éléments JSON simples.

Les déclarations logicielles sont incluses dans l'objet JSON demandeur à l'aide de ce membre OPTIONNEL :

software_statement Une déclaration logicielle contenant des valeurs de métadonnées client sur le logiciel client en tant que revendications. C'est une valeur de chaîne contenant l'intégralité du JWT signé.

Dans l'exemple suivant, certains paramètres d'enregistrement sont transmis en tant que revendications dans une déclaration logicielle de l'exemple de la section 2.3, tandis que certaines valeurs spécifiques à l'instance client sont transmises en tant que paramètres réguliers (avec des sauts de ligne dans les valeurs à des fins d'affichage uniquement) :

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. Réponses​

Suite à une demande d'enregistrement réussie, le serveur d'autorisation renvoie un identifiant client pour le client. Le serveur répond avec un code d'état HTTP 201 Created et un corps de type "application/json" avec un contenu tel que décrit à la section 3.2.1.

Suite à une demande d'enregistrement infructueuse, le serveur d'autorisation répond par une erreur, comme décrit à la section 3.2.2.

3.2.1. Réponse d'information client​

La réponse contient l'identifiant client ainsi que le secret client, si le client est un client confidentiel. La réponse PEUT contenir des champs supplémentaires tels que spécifiés par les extensions de cette spécification.

client_id REQUIS. Chaîne d'identifiant de client OAuth 2.0. Il NE DEVRAIT PAS être actuellement valide pour tout autre client enregistré, bien qu'un serveur d'autorisation PUISSE émettre le même identifiant client à plusieurs instances d'un client enregistré à sa discrétion.

client_secret OPTIONNEL. Chaîne de secret client OAuth 2.0. S'il est émis, cela DOIT être unique pour chaque "client_id" et DEVRAIT être unique pour plusieurs instances d'un client utilisant le même "client_id". Cette valeur est utilisée par les clients confidentiels pour s'authentifier auprès du point de terminaison de jeton, comme décrit dans OAuth 2.0 [RFC6749], Section 2.3.1.

client_id_issued_at OPTIONNEL. Heure à laquelle l'identifiant client a été émis. L'heure est représentée par le nombre de secondes à partir du 01-01-1970T00:00:00Z tel que mesuré en UTC jusqu'à la date/heure d'émission.

client_secret_expires_at REQUIS si "client_secret" est émis. Heure à laquelle le secret client expirera ou 0 s'il n'expire pas. L'heure est représentée par le nombre de secondes à partir du 01-01-1970T00:00:00Z tel que mesuré en UTC jusqu'à la date/heure d'expiration.

De plus, le serveur d'autorisation DOIT renvoyer toutes les métadonnées enregistrées sur ce client, y compris les champs provisionnés par le serveur d'autorisation lui-même. Le serveur d'autorisation PEUT rejeter ou remplacer l'une des valeurs de métadonnées demandées par le client soumises lors de l'enregistrement et les remplacer par des valeurs appropriées. Le client ou le développeur peut vérifier les valeurs dans la réponse pour déterminer si l'enregistrement est suffisant pour être utilisé (par exemple, le "token_endpoint_auth_method" enregistré est pris en charge par le logiciel client) et déterminer un plan d'action approprié pour le logiciel client. La réponse à une telle situation est hors du champ d'application de cette spécification, mais pourrait inclure le dépôt d'un rapport auprès du développeur de l'application ou du fournisseur de serveur d'autorisation, une tentative de réenregistrement avec des valeurs de métadonnées différentes ou diverses autres méthodes. Par exemple, si le serveur prend également en charge un mécanisme de gestion d'enregistrement tel que celui défini dans [RFC7592], le client ou le développeur pourrait tenter de mettre à jour l'enregistrement avec des valeurs de métadonnées différentes. Ce processus pourrait également être aidé par un protocole de découverte de service, tel que [OpenID.Discovery], qui peut répertorier les capacités d'un serveur, permettant à un client de faire une demande d'enregistrement plus éclairée. L'utilisation d'un tel système de gestion ou de découverte est facultative et en dehors du champ d'application de cette spécification.

La réponse d'enregistrement réussie utilise un code d'état HTTP 201 Created avec un corps de type "application/json" constitué d'un seul objet JSON [RFC7159] avec tous les paramètres en tant que membres de niveau supérieur de l'objet.

Si une déclaration logicielle a été utilisée dans le cadre de l'enregistrement, sa valeur DOIT être renvoyée inchangée dans la réponse avec d'autres métadonnées en utilisant le nom de membre "software_statement". Les éléments de métadonnées client utilisés à partir de la déclaration logicielle DOIVENT également être renvoyés directement en tant que valeurs de métadonnées client de niveau supérieur dans la réponse d'enregistrement (éventuellement avec des valeurs différentes, car les valeurs demandées et les valeurs utilisées peuvent différer).

Ce qui suit est un exemple de réponse non normative d'un enregistrement réussi :

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. Réponse d'erreur d'enregistrement de client​

Lorsqu'une condition d'erreur OAuth 2.0 se produit, telle que le client présentant un jeton d'accès initial invalide, le serveur d'autorisation renvoie une réponse d'erreur appropriée au type de jeton OAuth 2.0.

Lorsqu'une condition d'erreur d'enregistrement se produit, le serveur d'autorisation renvoie un code d'état HTTP 400 (sauf indication contraire) avec un type de contenu "application/json" constitué d'un objet JSON [RFC7159] décrivant l'erreur dans le corps de la réponse.

Deux membres sont définis pour inclusion dans l'objet JSON :

error REQUIS. Chaîne de code d'erreur ASCII unique.

error_description OPTIONNEL. Description textuelle ASCII lisible par l'homme de l'erreur utilisée pour le débogage.

D'autres membres PEUVENT également être inclus et, s'ils ne sont pas compris, ils DOIVENT être ignorés.

Cette spécification définit les codes d'erreur suivants :

invalid_redirect_uri La valeur d'un ou plusieurs URI de redirection est invalide.

invalid_client_metadata La valeur de l'un des champs de métadonnées client est invalide et le serveur a rejeté cette demande. Notez qu'un serveur d'autorisation PEUT choisir de remplacer une valeur valide pour tout paramètre demandé des métadonnées d'un client.

invalid_software_statement La déclaration logicielle présentée est invalide.

unapproved_software_statement La déclaration logicielle présentée n'est pas approuvée pour une utilisation par ce serveur d'autorisation.

Ce qui suit est un exemple non normatif d'une réponse d'erreur résultant d'un URI de redirection qui a été mis sur liste noire par le serveur d'autorisation (avec des sauts de ligne dans les valeurs à des fins d'affichage uniquement) :

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

Ce qui suit est un exemple non normatif d'une réponse d'erreur résultant d'une combinaison incohérente de valeurs "response_types" et "grant_types" (avec des sauts de ligne dans les valeurs à des fins d'affichage uniquement) :

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."
}
Dernière mise à jour le