4. Obtention de l'autorisation (Obtaining Authorization)

Pour demander un jeton d'accès (Access Token), le client obtient l'autorisation du propriétaire de ressource (Resource Owner). L'autorisation est exprimée sous la forme d'une autorisation (Authorization Grant), que le client utilise pour demander le jeton d'accès. OAuth définit quatre types d'autorisation : code d'autorisation (Authorization Code), implicite (Implicit), informations d'identification du mot de passe du propriétaire de ressource (Resource Owner Password Credentials) et informations d'identification du client (Client Credentials). Il fournit également un mécanisme d'extension pour définir des types d'autorisation supplémentaires.

4.1. Autorisation par code (Authorization Code Grant)

Le type d'autorisation par code d'autorisation (Authorization Code Grant Type) est utilisé pour obtenir à la fois des jetons d'accès et des jetons de rafraîchissement (Refresh Token) et est optimisé pour les clients confidentiels (Confidential Client). Comme il s'agit d'un flux basé sur la redirection, le client doit (MUST) être capable d'interagir avec l'agent utilisateur du propriétaire de ressource (généralement un navigateur Web) et capable de recevoir des requêtes entrantes (via redirection) du serveur d'autorisation.

     +----------+
     | Resource |
     |   Owner  |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |  User-   |                                 | Authorization |
     |  Agent  -+----(B)-- User authenticates --->|     Server    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---<|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Client |          & Redirection URI                  |
     |         |                                             |
     |         |<---(E)----- Access Token -------------------'
     +---------+       (w/ Optional Refresh Token)

Figure 3 : Flux de code d'autorisation (Authorization Code Flow)

Le flux illustré dans la figure 3 comprend les étapes suivantes.

(A) Le client lance le flux en dirigeant l'agent utilisateur du propriétaire de ressource vers le point de terminaison d'autorisation (Authorization Endpoint). Le client inclut son identificateur de client (Client Identifier), la portée demandée (Scope), l'état local (Local State) et un URI de redirection (Redirection URI) vers lequel le serveur d'autorisation renverra l'agent utilisateur une fois l'accès accordé ou refusé.

(B) Le serveur d'autorisation authentifie le propriétaire de ressource (via l'agent utilisateur) et établit si le propriétaire de ressource accorde ou refuse la demande d'accès du client.

(C) En supposant que le propriétaire de ressource accorde l'accès, le serveur d'autorisation redirige l'agent utilisateur vers le client en utilisant l'URI de redirection fourni précédemment (dans la demande ou lors de l'enregistrement du client). L'URI de redirection inclut le code d'autorisation (Authorization Code) et tout état local fourni précédemment par le client.

(D) Le client demande un jeton d'accès au point de terminaison de jeton (Token Endpoint) du serveur d'autorisation en incluant le code d'autorisation reçu à l'étape précédente. Lors de la demande, le client s'authentifie auprès du serveur d'autorisation. Le client inclut l'URI de redirection utilisé pour obtenir le code d'autorisation à des fins de vérification.

(E) Le serveur d'autorisation authentifie le client, valide le code d'autorisation et s'assure que l'URI de redirection reçu correspond à l'URI utilisé pour rediriger le client à l'étape (C). S'il est valide, le serveur d'autorisation répond avec un jeton d'accès et éventuellement un jeton de rafraîchissement.

4.1.1. Demande d'autorisation (Authorization Request)

Le client construit l'URI de demande en ajoutant les paramètres suivants au composant de requête de l'URI du point de terminaison d'autorisation en utilisant le format application/x-www-form-urlencoded.

response_type
Requis (REQUIRED). La valeur doit (MUST) être définie sur « code ».

client_id
Requis (REQUIRED). L'identificateur de client tel que décrit dans la section 2.2.

redirect_uri
Facultatif (OPTIONAL). Tel que décrit dans la section 3.1.2.

scope
Facultatif (OPTIONAL). La portée de la demande d'accès telle que décrite dans la section 3.3.

state
Recommandé (RECOMMENDED). Une valeur opaque utilisée par le client pour maintenir l'état entre la demande et le rappel. Le serveur d'autorisation inclut cette valeur lors de la redirection de l'agent utilisateur vers le client. Le paramètre devrait (SHOULD) être utilisé pour empêcher la falsification de requête intersite (Cross-Site Request Forgery) (voir section 10.12).

Le client dirige le propriétaire de ressource vers l'URI construite en utilisant une réponse de redirection HTTP ou d'autres moyens disponibles via l'agent utilisateur du propriétaire de ressource.

Par exemple, le client dirige l'agent utilisateur pour qu'il effectue la requête HTTP suivante (sauts de ligne supplémentaires uniquement à des fins d'affichage) :

GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com

Le serveur d'autorisation valide la demande pour s'assurer que tous les paramètres requis sont présents et valides. Si la demande est valide, le serveur d'autorisation authentifie le propriétaire de ressource et obtient une décision d'autorisation (accorder ou refuser l'accès).

Le serveur d'autorisation doit (MUST) déterminer comment authentifier le propriétaire de ressource (par exemple, nom d'utilisateur et mot de passe, cookie de session).

4.1.2. Réponse d'autorisation (Authorization Response)

Si le propriétaire de ressource accorde la demande d'accès, le serveur d'autorisation émet un code d'autorisation (Authorization Code) et le transmet au client en ajoutant les paramètres suivants au composant de requête de l'URI de redirection en utilisant le format application/x-www-form-urlencoded.

code
Requis (REQUIRED). Le code d'autorisation généré par le serveur d'autorisation. Le code d'autorisation doit (MUST) expirer peu de temps après son émission pour atténuer les risques de fuite. Une durée de vie maximale recommandée du code d'autorisation est de 10 minutes. Le client ne doit pas (MUST NOT) utiliser le code d'autorisation plus d'une fois. Si un code d'autorisation est utilisé plus d'une fois, le serveur d'autorisation doit (MUST) refuser la demande et devrait (SHOULD), si possible, révoquer tous les jetons précédemment émis sur la base de ce code d'autorisation. Le code d'autorisation est lié à l'identificateur de client et à l'URI de redirection.

state
Requis (REQUIRED) si le paramètre « state » était présent dans la demande d'autorisation du client. La valeur exacte reçue du client.

Par exemple, le serveur d'autorisation redirige l'agent utilisateur en envoyant la réponse HTTP suivante :

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
          &state=xyz

Le client ne doit pas (MUST NOT) ignorer les implications de sécurité décrites dans la section 10.12, y compris la gestion des erreurs.

4.1.2.1. Réponse d'erreur (Error Response)

Si la demande échoue (le propriétaire de ressource refuse l'accès ou la demande échoue), le serveur d'autorisation en informe le client en ajoutant les paramètres suivants au composant de requête de l'URI de redirection en utilisant le format application/x-www-form-urlencoded.

error
Requis (REQUIRED). Un code d'erreur ASCII [USASCII] unique. L'un des suivants :

• invalid_request - La demande manque un paramètre requis, inclut une valeur de paramètre non valide, inclut un paramètre plus d'une fois ou est autrement mal formée.

• unauthorized_client - Le client n'est pas autorisé à demander un code d'autorisation en utilisant cette méthode.

• access_denied - Le propriétaire de ressource ou le serveur d'autorisation a refusé la demande.

• unsupported_response_type - Le serveur d'autorisation ne prend pas en charge l'obtention d'un code d'autorisation en utilisant cette méthode.

• invalid_scope - La portée demandée est non valide, inconnue ou mal formée.

• server_error - Le serveur d'autorisation a rencontré une condition inattendue qui l'a empêché de traiter la demande. (Ce code d'erreur est nécessaire car un code d'état HTTP 500 Internal Server Error ne peut pas être renvoyé au client via une redirection HTTP.)

• temporarily_unavailable - Le serveur d'autorisation est actuellement incapable de traiter la demande en raison d'une surcharge temporaire ou d'une maintenance du serveur. (Ce code d'erreur est nécessaire car un code d'état HTTP 503 Service Unavailable ne peut pas être renvoyé au client via une redirection HTTP.)

error_description
Facultatif (OPTIONAL). Texte ASCII [USASCII] lisible par l'homme fournissant des informations supplémentaires. Utilisé pour aider le développeur client à comprendre l'erreur.

error_uri
Facultatif (OPTIONAL). Un URI identifiant une page Web lisible par l'homme avec des informations sur l'erreur. Utilisé pour fournir au développeur client des informations supplémentaires sur l'erreur.

state
Requis (REQUIRED) si le paramètre « state » était présent dans la demande d'autorisation du client. La valeur exacte reçue du client.

4.1.3. Demande de jeton d'accès (Access Token Request)

Le client effectue une demande au point de terminaison de jeton (Token Endpoint) en utilisant les paramètres suivants dans le corps de l'entité de requête HTTP en utilisant le format application/x-www-form-urlencoded.

grant_type
Requis (REQUIRED). La valeur doit (MUST) être définie sur « authorization_code ».

code
Requis (REQUIRED). Le code d'autorisation reçu du serveur d'autorisation.

redirect_uri
Requis (REQUIRED) si le paramètre « redirect_uri » a été inclus dans la demande d'autorisation de la section 4.1.1, et leurs valeurs doivent (MUST) être identiques.

client_id
Requis (REQUIRED) si le client n'est pas authentifié auprès du serveur d'autorisation.

Si le client a reçu des informations d'identification de client (ou d'autres exigences d'authentification de client ont été attribuées), le client doit (MUST) s'authentifier auprès du serveur d'autorisation comme décrit dans la section 3.2.1.

Par exemple, le client effectue la requête HTTP suivante en utilisant TLS (sauts de ligne supplémentaires uniquement à des fins d'affichage) :

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Le serveur d'autorisation doit (MUST) :

• Exiger l'authentification du client (pour les clients confidentiels ou les clients ayant reçu des informations d'identification de client)
• Authentifier le client si l'authentification du client est incluse
• S'assurer que le code d'autorisation est valide
• S'assurer que le paramètre « redirect_uri » est présent si inclus dans la demande d'autorisation décrite dans la section 4.1.1, et si inclus, s'assurer que leur valeur « redirect_uri » est identique à celle utilisée pour rediriger le client lors de l'obtention du code d'autorisation

4.1.4. Réponse de jeton d'accès (Access Token Response)

Si la demande d'autorisation est valide et autorisée, le serveur d'autorisation émet un jeton d'accès (Access Token) et un jeton de rafraîchissement (Refresh Token) facultatif comme décrit dans la section 5.1. Si la demande a échoué ou est non valide, le serveur d'autorisation renvoie une réponse d'erreur comme décrit dans la section 5.2.

Exemple de réponse réussie :

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

4.2. Autorisation implicite (Implicit Grant)

Le type d'autorisation implicite (Implicit Grant Type) est un flux de code d'autorisation simplifié optimisé pour les clients implémentés dans un navigateur à l'aide d'un langage de script tel que JavaScript. Dans le flux implicite, au lieu d'émettre un code d'autorisation au client, le client reçoit directement un jeton d'accès (Access Token) (en tant que résultat de l'autorisation du propriétaire de ressource). Le type d'autorisation est implicite car aucune information d'identification intermédiaire telle qu'un code d'autorisation n'est émise (qui serait utilisée plus tard pour obtenir un jeton d'accès), et est émise directement au client.

Lors de l'émission de l'autorisation implicite, le serveur d'autorisation n'authentifie pas le client. Dans certains cas, l'identité du client (Client Identity) peut être vérifiée via l'URI de redirection utilisé pour transmettre au client. Le jeton d'accès peut être exposé au propriétaire de ressource ou à d'autres applications sur le même appareil car il peut être encodé dans l'URI de redirection.

L'autorisation implicite améliore la réactivité et l'efficacité de certains clients (tels que les clients basés sur un agent utilisateur (User-Agent-Based Client), par exemple, une application s'exécutant dans un navigateur Web), généralement implémentés à l'aide de JavaScript. Cependant, ce compromis devrait (SHOULD) tenir compte de certaines implications de sécurité, notamment :

• Comme décrit dans les sections 10.3 et 10.16, le jeton d'accès est encodé dans l'URI de redirection au client dans le fragment URI, ce qui augmente le risque de fuite à un attaquant.
• Le serveur d'autorisation n'émet pas de jeton de rafraîchissement (Refresh Token).

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier     +---------------+
     |         -+----(A)-- & Redirection URI --->|               |
     |  User-   |                                | Authorization |
     |  Agent  -|----(B)-- User authenticates -->|     Server    |
     |          |                                |               |
     |          |<---(C)--- Redirection URI ----<|               |
     |          |          with Access Token     +---------------+
     |          |            in Fragment
     |          |                                +---------------+
     |          |----(D)--- Redirection URI ---->|   Web-Hosted  |
     |          |          without Fragment      |     Client    |
     |          |                                |    Resource   |
     |     (F)  |<---(E)------- Script ---------<|               |
     |          |                                +---------------+
     +-|--------+
       |    |
      (A)  (G) Access Token
       |    |
       ^    v
     +---------+
     |         |
     |  Client |
     |         |
     +---------+

Figure 4 : Flux d'autorisation implicite (Implicit Grant Flow)

Le flux illustré dans la figure 4 comprend les étapes suivantes :

(A) Le client lance le flux en dirigeant l'agent utilisateur du propriétaire de ressource vers le point de terminaison d'autorisation (Authorization Endpoint). Le client inclut son identificateur de client (Client Identifier), la portée demandée (Scope), l'état local (Local State) et un URI de redirection (Redirection URI) vers lequel le serveur d'autorisation renverra l'agent utilisateur une fois l'accès accordé ou refusé.

(B) Le serveur d'autorisation authentifie le propriétaire de ressource (via l'agent utilisateur) et établit si le propriétaire de ressource accorde ou refuse la demande d'accès du client.

(C) En supposant que le propriétaire de ressource accorde l'accès, le serveur d'autorisation redirige l'agent utilisateur vers le client en utilisant l'URI de redirection fourni précédemment (dans la demande ou lors de l'enregistrement du client). L'URI de redirection inclut le jeton d'accès dans le fragment URI.

(D) L'agent utilisateur suit les instructions de redirection en effectuant une demande à la ressource client hébergée sur le Web (Web-Hosted Client Resource), qui conserve les informations de fragment localement (généralement un document HTML fourni par la ressource client hébergée sur le Web). La ressource client hébergée sur le Web renvoie une page Web contenant un script (généralement JavaScript) capable d'extraire le jeton d'accès.

(E) L'agent utilisateur exécute le script localement et extrait le jeton d'accès.

(F) L'agent utilisateur transmet le jeton d'accès au client.

4.2.1. Demande d'autorisation (Authorization Request)

Le client construit l'URI de demande en ajoutant les paramètres suivants au composant de requête de l'URI du point de terminaison d'autorisation en utilisant le format application/x-www-form-urlencoded.

response_type
Requis (REQUIRED). La valeur doit (MUST) être définie sur « token ».

client_id
Requis (REQUIRED). L'identificateur de client tel que décrit dans la section 2.2.

redirect_uri
Facultatif (OPTIONAL). Tel que décrit dans la section 3.1.2.

scope
Facultatif (OPTIONAL). La portée de la demande d'accès telle que décrite dans la section 3.3.

state
Recommandé (RECOMMENDED). Une valeur opaque utilisée par le client pour maintenir l'état entre la demande et le rappel. Le serveur d'autorisation inclut cette valeur lors de la redirection de l'agent utilisateur vers le client. Le paramètre devrait (SHOULD) être utilisé pour empêcher la falsification de requête intersite (Cross-Site Request Forgery) (voir section 10.12).

4.2.2. Réponse de jeton d'accès (Access Token Response)

Si le propriétaire de ressource accorde la demande d'accès, le serveur d'autorisation émet un jeton d'accès (Access Token) et le transmet au client en ajoutant les paramètres suivants au composant de fragment de l'URI de redirection en utilisant le format application/x-www-form-urlencoded.

access_token
Requis (REQUIRED). Le jeton d'accès émis par le serveur d'autorisation.

token_type
Requis (REQUIRED). Le type de jeton tel que décrit dans la section 7.1. La valeur est insensible à la casse.

expires_in
Recommandé (RECOMMENDED). La durée de vie du jeton d'accès en secondes. Par exemple, la valeur « 3600 » indique que le jeton d'accès expirera une heure après son émission. Si omis, le serveur d'autorisation devrait (SHOULD) fournir la période d'expiration via d'autres moyens ou documenter la valeur par défaut.

scope
Facultatif (OPTIONAL) si identique à la portée demandée par le client; sinon, requis (REQUIRED). La portée du jeton d'accès accordé par le propriétaire de ressource.

state
Requis (REQUIRED) si le paramètre « state » était présent dans la demande d'autorisation du client. La valeur exacte reçue du client.

Le serveur d'autorisation ne doit pas (MUST NOT) émettre un jeton de rafraîchissement (Refresh Token) dans une réponse contenant un jeton d'accès.

4.3. Informations d'identification du mot de passe du propriétaire de ressource (Resource Owner Password Credentials Grant)

Le type d'autorisation par informations d'identification du mot de passe du propriétaire de ressource (Resource Owner Password Credentials Grant Type) devrait (SHOULD) être utilisé uniquement lorsque le propriétaire de ressource a une relation de confiance avec le client, tel que le système d'exploitation de l'appareil ou une application hautement privilégiée. Le serveur d'autorisation devrait (SHOULD) faire preuve d'une attention particulière lors de l'activation de ce type d'autorisation lorsque d'autres types d'autorisation ne sont pas disponibles.

Ce type d'autorisation convient aux clients capables d'obtenir les informations d'identification du propriétaire de ressource (nom d'utilisateur et mot de passe, généralement à l'aide d'un formulaire interactif). Il est également utilisé pour migrer des clients existants vers OAuth pour des raisons héritées ou de migration (par exemple, les clients qui stockaient directement les informations d'identification du propriétaire de ressource à l'aide de l'authentification HTTP Basic ou Digest) et les convertir en d'autres flux OAuth (plus sécurisés).

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          v
          |    Resource Owner
         (A) Password Credentials
          |
          v
     +---------+                                  +---------------+
     |         |>--(B)---- Resource Owner ------->|               |
     |         |         Password Credentials     | Authorization |
     | Client  |                                  |     Server    |
     |         |<--(C)---- Access Token ---------<|               |
     |         |    (w/ Optional Refresh Token)   |               |
     +---------+                                  +---------------+

Figure 5 : Flux d'informations d'identification du mot de passe du propriétaire de ressource

4.3.2. Demande de jeton d'accès (Access Token Request)

Le client effectue une demande au point de terminaison de jeton (Token Endpoint) en utilisant les paramètres suivants :

grant_type
Requis (REQUIRED). La valeur doit (MUST) être définie sur « password ».

username
Requis (REQUIRED). Le nom d'utilisateur du propriétaire de ressource.

password
Requis (REQUIRED). Le mot de passe du propriétaire de ressource.

scope
Facultatif (OPTIONAL). La portée de la demande d'accès telle que décrite dans la section 3.3.

4.4. Informations d'identification du client (Client Credentials Grant)

Le client peut (MAY) demander un jeton d'accès (Access Token) en utilisant uniquement ses informations d'identification de client (Client Credentials) (ou d'autres moyens d'authentification pris en charge). Le type d'autorisation par informations d'identification du client doit (MUST) être utilisé uniquement lorsque le client est le propriétaire de ressource ou lorsque le client demande l'accès aux ressources protégées sur la base d'une autorisation précédemment arrangée avec le serveur d'autorisation.

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

Figure 6 : Flux d'informations d'identification du client (Client Credentials Flow)

4.4.2. Demande de jeton d'accès (Access Token Request)

grant_type
Requis (REQUIRED). La valeur doit (MUST) être définie sur « client_credentials ».

scope
Facultatif (OPTIONAL). La portée de la demande d'accès telle que décrite dans la section 3.3.

4.5. Autorisations d'extension (Extension Grants)

Le client peut (MAY) utiliser un type d'autorisation d'extension (Extension Grant Type) pour demander un jeton d'accès (Access Token) en ajoutant les paramètres suivants au corps de l'entité de requête HTTP en utilisant le format application/x-www-form-urlencoded.

grant_type
Requis (REQUIRED). La valeur doit (MUST) être un URI absolu.

---