Token retrieval via the OAuth protocol

Prerequisite

Any client willing to use the OAuth protocol to perform operations on behalf of its users has to register his application on Mobilic API beforehand.

To do so, the client has to send an email at [e-mail], mentioning the following informations :

• requested environment (sandbox or production)

• application name

• redirect URLS list

Therefore, the client will receive a client_id and a client_secret, allowing the use of the OAuth2 module.

Protocol

OAuth2 protocol allows applications (client) used by road transportation companies to perform operations on Mobilic API (resource server) on behalf of their users (resource owner).

Practically speaking, OAuth method allows applications to retrieve access tokens on behalf on users, without knowing their passwords.

This page describes the procedure as it comes to implement the OAuth protocol and is written by Mobilic. It is not intended to cover all the details of the protocol itself. Many great resources regarding the protocol already exist online.

There are several OAuth protocols allowing a client to retrieve an access token.

Mobilic implement "Authorization Code Grant", detailed here and in this diagram :

 +----------+
 | 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)
 
 Note: The lines illustrating steps (A), (B), and (C) are broken into 
 two parts as they pass through the user-agent.
 
                  Figure 3: Authorization Code Flow

Here is the two entry points exposed by Mobilic:

• for production environment

  • Authorization URL: https://mobilic.beta.gouv.fr/oauth/authorize

  • Token URL: https://mobilic.beta.gouv.fr/api/oauth/token

• for sandbox environment

  • Authorization URL: https://sandbox.mobilic.beta.gouv.fr/oauth/authorize

  • Token URL: https://sandbox.mobilic.beta.gouv.fr/api/oauth/token

A. User redirection to the Mobilic authorization URL

The client starts the procedure by redirecting the user browser (or by opening a browser if the client application is not a web application) to Mobilic authorization URL.

The URL query string must contain the following items (cf https://tools.ietf.org/html/rfc6749#section-4.1.1):

• client_id: client ID provided by Mobilic API

• response_type: the value code

• redirect_uri: the chosen redirect URL

Example : https://mobilic.beta.gouv.fr/oauth/authorize?response_type=code&client_id=XXX&redirect_uri=http%3A%2F%2Fclient%2Eexample%2Ecom%2Fcallback

B. User authentification and explicit consent

Mobilic redirects the user to the authentification page (if not logged in) and then to the consent page.

The user (resource owner) has the choice to accept or deny the client access request:

french version screen showing the authorization pop-up with "allow" and "deny" options

C. Redirection to the client application with an authorization code

In the case where the user granted access, the browser is redirected to the redirect URL specified in the authorization request.

The redirect URL query string will contain an authorization code which stays valid 5 minutes.

Example : https://client.example.com/callback?code=XXX.

D. Request an access token in exchange for the authorization code

The client requests an access token with a POST request on the token URL.

The request must contain the following arguments, with the format application/x-www-form-urlencoded:

• grant_type=authorization_code

• code, the authorization code

• redirect_uri, redirect URL mentioned in the authorization request.

The request must also be authenticated with the client IDs. This can be done in two ways:

• adding the client_id and the client_secret as additional arguments in the POSTrequest

• adding the client_id and the client_secret in the header of the request with the basic method.

Example :

POST /api/oauth/token HTTP/1.1
Host: mobilic.beta.gouv.fr
Authorization: Basic XXX
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=YYY
&redirect_uri=https://client.example.com/callback

E. Access token retrieval

If the POST request to the token URL is valid, the response will contain an access token. More precisely, a JSON response with the following structure:

{
  "token_type": "Bearer",
  "access_token": "<TOKEN>"
}

On the contrary, if the request fails, the JSON response will get the following structure:

{
  "error": "<ERROR>"
}